home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 March - Disc 1 / Macworld (1999-03) (Disk 1).dmg / Shareware World / Utilities / Text Processing / Alpha / Help / Extending Alpha < prev    next >
Encoding:
Text File  |  1998-12-19  |  56.8 KB  |  1,382 lines  |  [TEXT/ALFA]
  1.  
  2.                     Writing New Modes, Menus and Packages
  3.  
  4.  
  5.                                               created: 97-03-03 11.44.50
  6.                                           last update: 19/12/1998 {11:04:32 pm}
  7.  
  8. Author:    Vince Darley, some pieces by Tom Fetherston and Pete Keleher
  9. E-mail:    <darley@fas.harvard.edu>
  10.   mail:    Division of    Engineering and Applied    Sciences, Harvard University
  11.         Oxford Street, Cambridge MA    02138, USA
  12.    www:    <http://www.fas.harvard.edu/~darley/>
  13.  
  14.  
  15.            Introduction
  16.  
  17. If you're writing or modifying any mode, menu or extension (collectively 
  18. known as packages) related Tcl code for use with Alpha, you should read this 
  19. document.  It also tells you how to make use of some of the features of 
  20. Vince's Additions in your mode.  These instructions pertain to all versions 
  21. of Alpha greater than or equal to 7.1.
  22.  
  23. There are two basic types of package which Alpha uses: modes, and 
  24. features.  A mode helps with editing a file for a particular purpose: 
  25. web pages use 'HTML' mode, C++ code uses 'C++' mode, LaTeX documents 
  26. use 'TeX' mode,… There are about 20 such modes currently available.  
  27. Features are of three types: menus, extensions and ordinary features.  
  28. A feature adds functionality to Alpha either globally (a 'global 
  29. feature') or just for particular modes (a 'mode feature').  Menus are 
  30. one type of feature used to extend Alpha.  Most modes add a menu which 
  31. is automatically attached to that mode.  Other menus are often useful 
  32. globally.  It's up to the user to decide when each feature/menu is 
  33. active.  Mode-authors can of course set the defaults for their mode.  
  34. Examples of globally useful menus are the filesets menu, the eudora 
  35. menu and the electric menu.  When you create a new menu for Alpha, you 
  36. have the option of suggesting that it is attached to particular modes, 
  37. or that it is suggested as global, or that it is global only.  General 
  38. features are organised in the same way, but don't create menus.  
  39. Finally, an extension is a simple form of feature which is either 
  40. globally active or off (it either doesn't make sense or isn't 
  41. particuarly useful to turn extensions on and off in a mode-dependent 
  42. way).  Examples of extensions are the printer choices sub-menu, or the 
  43. bib-engine (used to interact with BibTeX).  Note: a 'menu' is 
  44. something which sits in Alpha's menubar, at the top level.  A feature 
  45. or extension can create submenus which sit inside top level menus, but 
  46. these are not 'menus' in the same sense.  The main distinction is that 
  47. menus must be registered with 'alpha::menu' or 'addMenu', whereas 
  48. submenus need no special registration.
  49.  
  50. For the impatient reader: here's how to write a very simple feature 
  51. which contains one new procedure and one new key-binding (to that 
  52. procedure).  Just create a file which looks like this:
  53.  
  54.     # (auto-install) --- this line will cause Alpha to try to install 
  55.     # this pkg when this file is opened outside of Alpha's folder hierarchy
  56.     
  57.     alpha::feature myPackage 0.1 {C C++} {
  58.         # no global initialisation required
  59.     } {
  60.         # activation script
  61.         # bind the 'x' key to my procedure (not a good idea ;-)
  62.         Bind 'x' myProcedure
  63.     } {
  64.         # deactivation script
  65.         unBind 'x' myProcedure
  66.     } uninstall {this-file} maintainer {
  67.         "My Name" my@email http://webpage..
  68.     } help {
  69.         Binds the blah-key to 'myProcedure' which carries out...
  70.         
  71.         This package is only designed to do something useful in
  72.         C and C++ modes.
  73.     }
  74.     
  75.     proc myProcedure {} {
  76.         # do some cool stuff
  77.     }
  78.     
  79. Save this file on your desktop (say), and open it.  You'll see Alpha
  80. automatically opens an installation dialog, puts this file in the
  81. right place if you agreed to the installation, and rebuilds its
  82. package and tcl indices so that this package can be used next time
  83. you restart Alpha (actually with a simple package like this, you can
  84. use it straight-away).  By default this package declares it is useful
  85. for C and C++ modes, although the user could choose to activate the
  86. package globally or individually for any set of modes.
  87.  
  88. Important note: if you're writing a mode, menu or package, you should 
  89. know about the 'package index'.  Alpha keeps a cache of all startup 
  90. information, so that if you edit your 'alpha::mode ...' statement, and 
  91. quit and restart Alpha, the changes will not take effect.  You must
  92. tell Alpha to rebuild the package indices before quitting.
  93.  
  94. Alpha provides lots of cool facilities to help you write useful
  95. packages, whether they are modes, menus or extensions.  This
  96. document describes those facilities.
  97.  
  98.              Guidelines for future Tcl 8 compatibility
  99.  
  100. This section is only useful if you're concerned about making
  101. future transitions easier, and has no relevance for writing
  102. code for Alpha 7.1 at present.  However, since Alpha will be upgraded
  103. to Tcl 8 for the next major release (no date yet!), knowing some of
  104. this may save you trouble later.  It will also help you to understand
  105. how to write code which works efficiently with Tcl 8, making maximum use of 
  106. the potential speed improvements there.
  107.  
  108. When Alpha upgrades to Tcl 8, some changes to your code may be necessary, 
  109. unless you pay attention to a few simple details.  First, any proc which 
  110. contains '::' is a procedure defined inside a namespace.  Tcl 8 requires 
  111. you to declare namespaces in advance.  Hence unless Tcl 8 knows about 
  112. namespace 'A', say, defining a procedure 'proc A::blah ...'  is an error.  
  113. You should therefore include the line 'namespace eval A {}' at the 
  114. beginning of the file defining all the 'A::' procedures.  (Alpha 7.1 will 
  115. ignore these namespace commands so your code works either way)
  116.  
  117. The second guideline concerns the way namespaces actually work.
  118. Assume you have defined two procedures 'A::open' and 'A::list'.
  119. Let's say: 
  120.  
  121.     proc A::list {} { open [file join $HOME Help Changes] w ; ...}
  122.     proc A::open {} { return [list a b c] }
  123.  
  124. Then both of these procedures will fail (and may crash Alpha) if 
  125. running Tcl 8.  This is because inside the procedures we're in the 'A' 
  126. namespace and this means commands are checked first to see if they 
  127. exist inisde that namespace.  Therefore command 'open' in A::list is 
  128. not the global Tcl command 'open', rather it is the procedure A::open 
  129. (obviously not what was intended above).  Similarly 'list' in A::open 
  130. is in fact the procedure A::list.  There are two ways to resolve this: 
  131. (i) write 'list' as '::list' inside the proc (and 'open' as '::open'), 
  132. or (ii) ensure the tail end of your procedures do not clash with any 
  133. global Tcl commands.  The first option will not work in Tcl earlier 
  134. than 8.0, which means you'd have to supply two different definitions 
  135. of the procedure and use 'if {[info tclversion] < 8.0} ...'  to create 
  136. the correct one.  The second option will work without modification, 
  137. and is therefore somewhat preferable.
  138.  
  139. By following these two guidelines, your code should continue to work
  140. without any changes _at all_, when Alpha upgrades (except that your
  141. code will run 2-10 times faster!).
  142.  
  143. If you're really concerned about maximum efficiency in Tcl 8, make
  144. sure you always use '{}' with both 'if' and 'expr'.  This speeds things
  145. up with Tcl 8 due to some technical aspects of the way the Tcl compiler
  146. works (see http://www.scriptics.com for details).  For example don't
  147. write 'if [expr 1+2 == 3] ...' but rather 'if {[expr {1+2 == 3}]}'.
  148.  
  149. A very important pointer for speed in Tcl 8 is that lists are very fast.
  150. This means using 'lappend', 'lindex' etc is very quick.  There is one
  151. small point you should obey: never use 'if {$myList == ""} {...}' to see
  152. if a list is empty.  Instead use 'if {![llength $myList]} {...}'.  Until
  153. Tcl implements some good optimisation in the internal compiler (which it
  154. may never do), the former expression will slow your code down hugely when
  155. the list isn't empty.
  156.  
  157. The behaviour of [file tail] has changed slightly between 7.5 and 
  158. 8.0; with 7.5 [file tail a:b:] was "", but 8.0 returns "b".  Try to write 
  159. code which doesn't depend on this distinction.
  160.  
  161.              Declaring your package to Alpha
  162.  
  163. A package must contain, preferably as its first non-comment line (this 
  164. is important), a statement like this:
  165.  
  166.     alpha::mode NAME VERSION ...
  167.     
  168.     alpha::menu NAME VERSION ...
  169.     
  170.     alpha::feature NAME VERSION ...
  171.     
  172.     alpha::extension NAME VERSION ...
  173.     
  174. (The other parameters to these commands are explained below).  The name will 
  175. identify your package, and for modes must be at most 4 characters long.  
  176. It should not contain any spaces (this limitation may be lifted in a future 
  177. version of Alpha).  The version is a string of the form 1.0.1, or 2.3b1 or 
  178. 1.4.530.1.3a5.  Modes, menus and extensions take different arguments for the 
  179. remainder of the 'alpha::' declaration line, but each ends in a script which 
  180. Alpha scans and stores for you (Alpha scans all installed files for 
  181. package declaration lines and caches this information so that at startup, 
  182. no files need be read).  For modes and menus, this script is executed 
  183. automatically at startup.  For features, there are initialisation and 
  184. activation/deactivation scripts.  An extension is a simpler form of a 
  185. feature which only has a single initialisation script (used the first 
  186. time it is activated).  Package initialization occurs in the order: modes, 
  187. menus and finally extensions.
  188.  
  189. IMPORTANT: The declaration command must not be wrapped in any 'catch' 
  190. statements.  This is necessary to allow Alpha to rebuild package 
  191. indices rapidly (note that it is no longer required to be at the 
  192. beginning of the line).  If you wish to write backwards compatible code, 
  193. try something like:
  194.  
  195.     if {[info commands alpha::extension] != ""} {
  196.         alpha::extension ...
  197.     } else {
  198.         # initialize in some old way for Alpha 6.x
  199.     }
  200.  
  201. Your package will not function properly if you don't obey the above 
  202. guidelines.  Alpha itself is considered a package, with a version
  203. number, so that your code can request a particular version of Alpha.
  204. Alpha's version number also has a patchlevel which will be updated
  205. with each Tcl-only patch release.  Hence you can write:
  206.  
  207.     alpha::package require Alpha 7.1b1
  208.  
  209. For the first Alpha 7.1 beta release, and
  210.  
  211.     alpha::package require Alpha 7.1p1
  212.  
  213. If your package actually requires some fixes from the first patch 
  214. release after the final 7.1 release.  You can similarly require 
  215. particular versions of other packages.  You should 'require' as old a 
  216. version as possible, so that you don't force users to upgrade 
  217. unnecessarily.
  218.  
  219. Note that with the advent of the new alpha:: commands, it is no longer
  220. necessary to place modes, menus and packages in their separate directories:
  221. they can go anywhere on the auto-path.  However it is more convenient to
  222. store them separately most of the time.
  223.  
  224.              The developer utilities package
  225.  
  226. You will want to download this package, since it helps with a number
  227. of developer-related tasks:
  228.  
  229. •    distribution archival, compression, and uploading
  230. •    colouring and hyperlinking Help files (like this one)
  231.  
  232. For anyone helping with Alpha's core distribution it also allows:
  233.  
  234. •    colouring Alpha's manual, commands, readme and changes files
  235.  
  236. ===============================================================================
  237.            
  238.            Writing New Modes
  239.  
  240. To add a mode to Alpha, a file (usually ending with 'Mode.tcl') must be 
  241. created and placed in the ":Tcl:Modes" directory.
  242.  
  243. The file should begin with a construct of the following form:
  244.  
  245.     alpha::mode Perl 1.3 dummyPerl {*.pl *.ph *.pm} {
  246.         perlMenu electricBraces electricReturn 
  247.     } {
  248.         addMenu perlMenu •132 Perl
  249.     }
  250.  
  251. This command is very, very important.
  252.  
  253.     alpha::mode <mode> <version> <dummyProc> <suffixes> <mode-features> <script>
  254.     
  255. defines a new mode.  When trying to switch to the Perl mode, Alpha will 
  256. attempt to execute the function 'dummyPerl'.  The suffixes allow Alpha to 
  257. automatically determine the correct mode of a newly opened file.  In this
  258. case the script contains the single command:
  259.  
  260.     addMenu <mname> ?<name>? ?<pertains to modes>?
  261.  
  262. which defines a new menu, with 'name' the visible name of the menu (names 
  263. which start with '•' indicate Alpha should use an icon resource with the 
  264. given number.  Icon number 132 is the Perl camel icon).  This menu can be 
  265. used in any mode, although by default, it is only attached to Perl mode.  
  266. 'mname' is actually a variable which contains (will contain) the real menu 
  267. name (in this case '•132').  The third argument usually contains a 
  268. single mode with which this menu is distributed.  Its use is mainly so that
  269. Alpha knows that this menu belongs primarily to this mode, so that if the user
  270. asks for information on the menu, Alpha knows to respond with 
  271. information on the mode instead (curiously Alpha wouldn't otherwise 
  272. know).
  273.  
  274. Perhaps the MOST important part of the above code is the existence of the
  275. 'dummyProc'.  When this proc is called, the result must be that all of 
  276. the mode's preferences are declared.  In other words, the dummyProc
  277. should normally be in the same file as the mode's 'newPref' declarations.
  278. This is important because almost directly after that call, Alpha expects
  279. all of the mode's preferences to be stored in the ${mode}modeVars array,
  280. which will only be true if all of the newPref commands have been evaluated.
  281.  
  282. Here is an example from Diff mode:
  283.  
  284.     alpha::mode Diff 1.0 diffMenu {*.diff} {diffMenu} {
  285.         addMenu diffMenu •288
  286.         menu::insert Utils submenu 0 compare
  287.         menu::insert compare items end "windows" "files…" "directories…"
  288.     } uninstall {
  289.         removeFile "$pkg_file"
  290.         removeFile [file join ${HOME} Tools "GNU Diff"]
  291.     } maintainer { "Vince Darley" darley@fas.harvard.edu http://... }
  292.  
  293. The 'uninstall' and 'maintainer' sections are optional, and explained later.  
  294. Here is a more complex example for Python mode:
  295.  
  296.     # ◊◊◊◊ minalmalist mode set-up ◊◊◊◊ #
  297.     alpha::mode Pyth 0.2 dummyPython {*.py *.pyc *.pyi} PythonMenu {
  298.         addMenu PythonMenu
  299.         #To set the mode from a unix-like "#!python" first line
  300.         set unixMode(python) {Pyth}
  301.     }
  302.     # dummy proc to load this mode.  
  303.     proc dummyPython {} {}
  304.     # dummy proc to load the code to make the PythonMenu 
  305.     proc PythonMenu {} {}
  306.     # rest of mode's code follows...
  307.     
  308.     #Lets the automatic comment insertion/continuation
  309.     # routines function with this mode. 
  310.     set Pyth::commentCharacters(General) "\#"
  311.     set Pyth::commentCharacters(Paragraph) [list "## " " ##" " # "]
  312.     set Pyth::commentCharacters(Box) [list "#" 1 "#" 1 "#" 3]
  313.     
  314. The package declaration should contain all code which is necessary to 
  315. recognise a given file as belonging to that mode (hence the use
  316. of 'unixMode' for python), which will then make Alpha call the
  317. dummyProc which will auto-load the entire file.  Other information,
  318. such as the 'commentCharacters' entries above should not go in the
  319. package declaration.
  320.     
  321. Notice that there are two types of 'dummy' proc: each menu Alpha uses
  322. should have a proc of the same name associated with it.  This proc is
  323. called by Alpha _each_ time Alpha tries to insert the menu into the
  324. menubar.  The proc can be empty (as above), or could actually do
  325. something if desired.  The second kind of dummy proc is the 'mode'
  326. dummy proc, given in the 'alpha::mode' command.  Here it is called
  327. 'dummyPython'.  Alpha calls this proc each time it switches to Pyth
  328. mode.  Again the proc can do something if desired, but will usually
  329. be empty.  If both procs are empty, as above, one can of course
  330. just use one proc (called PythonMenu in this case), and replace the
  331. alpha::mode line by:
  332.  
  333.     alpha::mode Pyth 0.2 PythonMenu {*.py *.pyc *.pyi} PythonMenu
  334.  
  335. The only advantage of this approach is that it saves a small amount
  336. of memory (you can delete the 'dummyPython' proc from the file). Note that 
  337. this only holds true for modes whose Tcl code is in one file.
  338.     
  339.              Multi-file modes
  340.  
  341. Modes that consist of more than a single file should no longer use a source 
  342. statement that assumes that the other files for the mode will be in 
  343. $HOME:Tcl:Modes.  The best solution is to use Alpha's standard auto-loading 
  344. capability which will source a file when it needs a procedure which is 
  345. contained in that file.  If you must use 'source' manually, you can use 
  346. 'file dirname [procs::find someProcInThisFile]' to get the current 
  347. directory.  Your other files should also be there.
  348.  
  349. A convenient way of implementing your multi-file loading is to create
  350. procs with the same name as the file at the beginning of each file.
  351. Then to load the file you just do 'catch "filename"'.  For example
  352. if there is a proc defined 'proc perl5.tcl {} {}' at the start of
  353. the file "perl5.tcl", then I can auto-load that file by having the 
  354. following code in "perlMode.tcl" (note: actual code differs slightly):
  355.  
  356.     if {[catch perl5.tcl]} { 
  357.         alertnote "Problem loading 'perl5.tcl'" 
  358.     }
  359.  
  360. Remember, you don't necessarily need to source all your mode/pkg's files in 
  361. one go.  Tcl is designed to source files for you when they are needed (when 
  362. a procedure contained in one of them is called).  Hence you only need to 
  363. source files which are required immediately (to set up some data, variables, 
  364. menus etc.)  and not everything else.  It is usually best to have a single 
  365. file which contains all the initialization code, and let any other files be 
  366. auto-loaded as necessary.
  367.  
  368.  
  369.              Use of the term "electric"
  370.  
  371. Through out the documentation and in actual proc names, you will see the use 
  372. of the word "electric", so a note on its usage might be helpful. 
  373. "Electric" is used in the sense of "automatic, power assisted behaviour", it is 
  374. intended to save time, keystrokes, and brainpower. Such behaviour is usually
  375. invoked by certain keystrokes (determined by various preference settings).
  376.  
  377.  
  378.              Mode procs
  379.  
  380. The following procs are either required or desired for a mode to be
  381. fully functional within Alpha.
  382.  
  383. Marking Proc's:        (provide indexes into code via '{}' and "M' pop-ups)
  384.  
  385.     <mode>::parseFuncs   -- (not every mode provides this one)
  386.     <mode>::MarkFile
  387.     
  388. Info providers:        (drive & support access to source or file related info)
  389.  
  390.     <mode>::DblClick    -- usually provides term specific help
  391.     
  392.     <mode>::optionTitlebar    -- provides menu to access related files
  393.     <mode>::optionTitlebarSelect    -- action for menu selection above
  394.     
  395. electric behaviour:    (these assist formatting & and save on keystrokes)
  396.  
  397.     <mode>::carriageReturn    -- this, supported by the following two, help
  398.                             --  to keep indentation standard (indirectly 
  399.                             --  called by a carriage return.
  400.     <mode>::indentLine -- indents a line, usually by calling next proc,
  401.                        -- and then inserting spaces/tabs as appropriate.
  402.     <mode>::correctIndentation -- allows smart-paste package to function
  403.  
  404.   -- These provide electric behaviour for '{', '}', and ';' respectively.
  405.   --  Their use is primarily for languages that use '{' and '}' for code
  406.   --  blocks, and ';' as the line terminator. They are indirectly called 
  407.   --  by the key they correspond to, and then, only if a corresponding mode 
  408.   --  preference flag has been defined and set to one. 
  409.   --                      (see 'Electric braces and semicolons below)
  410.   
  411.     <mode>::electricLeft
  412.     <mode>::electricRight
  413.     <mode>::electricSemi
  414.  
  415. Have a look at a standard mode like Tcl or C++ to see what these
  416. should do.  <mode>::correctIndentation must not fail (the correct
  417. indentation always exists for a line, so Alpha expects the proc to
  418. return a number and not signal an error).
  419.     
  420.              Hooks
  421.  
  422. Do not do all that 'rename saveHook mySaveHook'... stuff.  Use 
  423. 'hook::register' instead. See the file "hook.tcl" for details, but all
  424. you need to do is add lines like these:
  425.  
  426.     hook::register saveHook modified "C" "C++"
  427.     hook::register saveHook modified "Pasc"
  428.     hook::register saveHook htmlLastModified HTML
  429.     hook::register savePostHook codeWarrior_modified "C++" "C"
  430.     hook::register savePostHook ftpPostHook
  431.     hook::register saveasHook htmlLastModified HTML
  432.  
  433. Here's the general form
  434.  
  435.     hook::register 'hook-name' 'your proc' 'mode' ?... 'mode'?
  436.  
  437. If you don't include a 'mode', then your proc will be called no
  438. matter what the current mode is.   Avoid this unless absolutely
  439. necessary.  Here are the current hooks:
  440.  
  441.     activateHook changeMode closeHook deactivateHook modifyModeFlags 
  442.     quitHook resumeHook saveasHook saveHook savePostHook suspendHook
  443.     openHook
  444.  
  445. There's also a 'mode::init' hook which will be called the first
  446. time a mode is started up.  Note that at that time, the mode exists, but its
  447. variables have not yet been made global, and its menus have not
  448. yet been inserted into the menu bar.
  449.  
  450. There's also a 'startupHook' which is called when Alpha starts
  451. up, but after all other initialization has taken place, a 'launch'
  452. hook which is called when Alpha launches another application
  453. (register with hook::register launch yourproc $sig).
  454.  
  455.              Smart mode lines
  456.     
  457. If your mode will want to be able to use the first line of a file to 
  458. determine what mode a file should be opened up in, you need to tell 
  459. alpha what word in the first line should trigger that mode:
  460.     
  461.     set unixMode(python) {Pyth} 
  462.  
  463. A good place to do this is in the body of the your mode's package 
  464. declaration "alpha::mode … {…" statement (see example for Python above).  
  465. Note that the presence of the word itself is not sufficient; it must be of 
  466. the form '#!\usr\..\python' as is common on Unix (where it tells the shell 
  467. with what application to run the script)
  468.  
  469. Note that there is already built in support for opening a file in a given 
  470. mode if the first line contains:
  471.  
  472.     -*-<mode_label>-*-
  473.     
  474. e.g.:
  475.  
  476.     -*-Tcl-*-
  477.  
  478. Also, if the first line contains:
  479.  
  480.     (nowrap)
  481.  
  482. then you will not be asked if you want to see such a file in paragraph 
  483. format simplly because the lines have gotten so long alpha thinks they 
  484. might be from an application that maintains a paragraph as one long line 
  485. and does its own wrapping internally.
  486.  
  487.  
  488.              Mode creator types
  489.     
  490. If your mode wants to declare itself as a default for files with a 
  491. particular creator, (so any file with that creator opens up in that mode) 
  492. you need to tell Alpha with an entry whoses format is like this:
  493.     
  494.     set modeCreator(<4_char_creator_code>) <mode_label>
  495.  
  496. e.g.:
  497.  
  498.     set modeCreator(McPL) Perl
  499.  
  500. A good place to do this is in the body of the your mode's package 
  501. declaration "alpha::mode … {…" statement.
  502.  
  503.              Comment characters
  504.  
  505. If your mode will want to use the standard Alpha comment/uncomment
  506. block procedures, file headers, ... you need to tell Alpha what
  507. characters are used for comments.  Rather than redefining 
  508. the procedure 'commentCharacters', you should just define the following 
  509. variables:
  510.     
  511.     set ${mode}::commentCharacters(General) [list "*" "//"]
  512.     set ${mode}::commentCharacters(Paragraph) [list "/* " " */" " * "]
  513.     set ${mode}::commentCharacters(Box) [list "/*" 2 "*/" 2 "*" 3]
  514.     
  515. where the values shown are for C++ mode.  If you do this then there is
  516. no need to mess with the commentCharacters procedure.  (In general it
  517. is best if your mode does not need to redefine procedures in Alpha's core).
  518.  
  519.              Paragraph definitions
  520.  
  521. Paragraph filling.  You can set the variables:
  522.  
  523.     set ${mode}::startPara {^(.*\{)?[ \t]*$}
  524.     set ${mode}::endPara {^(.*\})?[ \t]*$}
  525.  
  526. to customize your mode's paragraph definition.  The above example's regular 
  527. expressions (third 'word') are for Tcl code.
  528.  
  529. Alpha uses these to determine what it should act on when it is requested to 
  530. re-wrap, make a selection or navigate with respect to paragraphs.  
  531.  
  532. Note that currently the wrapping routines take no notice of code formatting 
  533. rules and are limited utility outside of the 'Text' mode.  The only proc's 
  534. that use these are found in "textFill.tcl".
  535.  
  536.              Electric braces and semicolon
  537.  
  538. If your mode uses electric '{', '}', ';' (i.e. characters that end the 
  539. current line and indent the next one automatically) you need to define 
  540. a few procedures: '${mode}::electricLeft', '${mode}::electricRight' 
  541. and '${mode}::electricSemi' which will be called automatically (you do 
  542. NOT need to bind anything to the keys).  If you do not define these 
  543. procedures, Alpha will use a default electric procedure which works 
  544. pretty well for C, Perl and Java code.
  545.  
  546. Of course the user needs to turn on the electric functionality for
  547. your mode.  (Activate by default by including 'electricBraces' in 
  548. your list of mode features in the alpha::mode command).
  549.  
  550. Do not bind to '{', '}' or ';' if you want these to be electric. Alpha
  551. will automatically call your mode's procedures if they are named
  552. correctly.
  553.  
  554.              Option-click-titlebar menu
  555.  
  556. If your mode has a specific 'opt-titlebar-click' menu, you need to
  557. define the procedures:
  558.     
  559.     proc C++::OptionTitlebar {} {
  560.         # returns list of items for the menu
  561.     }
  562.     proc C++::OptionTitlebarSelect {item} {
  563.         # carries out the mode-specific action when 'item' is selected.
  564.     }
  565.  
  566.              Electric code templates
  567.     
  568. If you mode wants to insert text into the window which contains template 
  569. stops (usually bullets '•' in Alpha), so that the user can move from
  570. one to the next using the standard Alpha template packages (Alpha comes with 
  571. a basic one, and more sophisticated ones build upon the same 
  572. infrastructure), the you should insert template text with:
  573.  
  574.     elec::Insertion "blah blah •• blah blah"
  575.  
  576. This is a simple example with a single template stop.  Template stops are 
  577. noted with a pair of bullets (even though only one appears in the text).  
  578. You can place between the pair of bullets some more information about the 
  579. template stop, for instance:
  580.  
  581.     elec::Insertion "while \{•condition•\} \{\r\t•while body•\r\}\r••"
  582.  
  583. would be useful to insert a typical Tcl 'while' loop.  The template
  584. packages can prompt the user with the explanatory text making code 
  585. entry a little bit easier.
  586.  
  587. The 'elec::Insertion' routine works just like 'insertText' except it treats 
  588. any item •PROMPT• as a template stop called 'PROMPT'.  This procedure takes 
  589. a variable number of arguments, just like 'insertText'.  It has one further 
  590. side-effect.  If there are any stops in the block, then the cursor is 
  591. positioned at the first such stop.  Hence you don't need to do this: set p 
  592. [getPos] ; insertText "blah..."  ; goto $p ; nextTabStop Instead you just do 
  593. 'elec::Insert "blah..."'.  Note that the procedure 'nextTabStop' no longer 
  594. exists.  Use "ring::+", "ring::-" etc.  to move amongst tab stops.  The 
  595. basic Alpha distribution contains only basic template support.  Install 
  596. Vince's Additions to extend this support to persistent stops, with 
  597. user-prompting in the text or status bar,...  You don't have to change your 
  598. code to take advantage of the features of V'sA. It comes for free if you use 
  599. 'elec::Insertion' etc.
  600.  
  601. If you wish to use electric templates, avoid binding anything to the 'tab' 
  602. key or the 'j' key (also opt-tab, cmd-tab,…).  Such bindings may conflict
  603. with the electric bindings.
  604.  
  605. To use electric templates, you'll want to add electricTab to your
  606. list of default mode-features (or you can leave it for the user to
  607. activate).  If your mode never wants the Tab key to indent, then 
  608. define a dummy '<mode>::indentLine' proc which is empty: 
  609. 'proc <mode>::indentLine {} {}'.
  610.  
  611.              Electric return
  612.  
  613. This allows pressing return to indent correctly for the following line 
  614. so you may begin typing immediately.  To use this simply list this 
  615. package in your mode's 'mode-features' list and, do _not_ bind to the 
  616. return key.
  617.  
  618.              Automatic indentation
  619.  
  620. Two variables are associated with a window's indentation scheme: 
  621. 'indentationAmount' and the window's tab-size (which can be read
  622. with 'getWinInfo' or 'text::getTabSize').  If you are writing a custom 
  623. indentation routine, the procedure 'indent::setup' will be useful 
  624. to handle all these choices for you.  Look at the relevant section
  625. of "globals.tcl" to see what that procedure sets up for you.  Most
  626. people user either tab-size = indentation-amount = 4 spaces, OR
  627. tab-size = 8, indentation-amount = 4 spaces.  These cases are quite
  628. different, and it's nice if your mode allows the user to work with
  629. their preferred setup.
  630.  
  631.              The marks menu
  632.  
  633. Each mode has a procedure <mode>::MarkFile which is called to create the
  634. popup 'M' menu of marks.  There is a global flag 'quietlyClearMarks'
  635. which is set to 1 which dictates that the marks should be rebuilt
  636. without prompting the user as necessary.  You can add a mode-pref
  637. to over-ride this if you want.
  638. Just what text-patterns are used to trigger the formation of a 'namedMark' 
  639. (kept in the resource fork), its name, text position and extent, and the 
  640. order in which they are present in the menu, is all determined by the 
  641. <mode>::MarkFile your procedure.
  642.  
  643. For computer language editing modes, the common convention was to create an 
  644. index by routine names for each routine defined in the file, and to present 
  645. it in alphabetical order. The more current convention is to either 
  646. hardwire, or present the user with the option of listing the routine names 
  647. in the order in which they were defined in the file, indented under the 
  648. name of the code section in which it was defined. 
  649.  
  650. The Tcl mode is a good example of the above, by default the defined Tcl 
  651. proc's are presented in alphabetical order.  However if you check the 
  652. 'StucturalMarks' flag in Tcl's mode preferences, you get an index with the 
  653. above format (after regenerating the index via the 'MarkFile' menuitem).  
  654. If you organize your Tcl code into sections of logically or functionally 
  655. related proc's, and then give them a short header by using the 
  656. 'InsertDivider' option under the Tcl Menu, you have an index that can be 
  657. used to quickly get to a procedure when remember its position or 
  658. functionality more than you do its exact name.
  659.  
  660. Of course, it is still often the case that you remember the name and just 
  661. want to get to it quickly via an alphabetical index, so modes that use the 
  662. above scheme usually provide an alphabetical listing via the '{}' popup, 
  663. which is located right above the 'M' popup (see next topic).
  664.  
  665. Power User tip: cmd-clicking anywhere in a window's titlebar (except the 
  666. exact center), or in the "bevel'ed frame" will give you the same menu as 
  667. the 'M' popup. Using the sides of the window lets you access a particular 
  668. area of the menu quicker as you can cmd-click in the approximate location 
  669. of the index you want to go to. Additionally, if the window is flush 
  670. against the lefthand edge of your monitor, it is easier to 'crash' your 
  671. cusor into that edge and summon up the mark menu than it is to hit a eight 
  672. inch square button.
  673.  
  674.              The '{}' popup menu
  675.  
  676. This popup menu can be put to whatever use the mode author wants. If your 
  677. are useing the scheme mentioned in the above section, it is good to use 
  678. this popup to present an alphabetical listing of the routines. Some modes 
  679. add extras such as indicating the number of arguments a routine expects 
  680. (see Tcl), whether a argument is a 'reference' or a 'value' pass (see the 
  681. M2, i.e. modula mode) or anything else that might be useful. Languages that 
  682. use multi-part (qualified) identifiers may name the first part of a group 
  683. of indentifiers and indent the rest of the identifiers that share that 
  684. first part under it.
  685.  
  686. Power user tip: cmd-opt-<K> will put up a listpick dialog of the indexes 
  687. under the '{}' popup, as this is usually alphabetical you can type the 
  688. starting letters of the index you want to go to. (note: see 'Emacs Help' 
  689. for some other tips to navigate any scrolling list dialog box.)
  690.  
  691.  
  692.  
  693.              <mode>Completions.tcl
  694.  
  695. Each mode can have a completions file for use by the 'elecCompletions' 
  696. package (part of Vince's Additions or available separately).  To use
  697. this, place the appropriate definitions in a file called 
  698. '<mode>Completions.tcl'.  The installer will place such files in the 
  699. 'Completions' directory automatically (provided you don't put them in 
  700. a sub-folder of your distribution), and they will also be sourced
  701. automatically the first time a file opens in your mode.  There is
  702. therefore no need for you to source the file yourself.
  703.  
  704. ===============================================================================
  705.  
  706.            Writing new menus
  707.  
  708. New menus are placed in ":Tcl:Menus", and contain a start-up
  709. section of much the same form as a mode or feature:
  710.  
  711.     alpha::menu ftpMenu    0.3 global "•141" {
  712.         # One-time initialisation script 
  713.         
  714.         # here we do nothing
  715.     } {
  716.         # Activation script
  717.         
  718.         # here we do the standard thing of calling the menu proc
  719.         ftpMenu
  720.     } {
  721.         # Deactivation script
  722.     }
  723.     # proc ftpMenu to auto-load
  724.     proc ftpMenu {} {}
  725.  
  726. The 'global' parameter tells Alpha that this menu isn't associated with
  727. any particular mode (otherwise you can replace 'global' by a list of 
  728. modes possibly including the global keyword, e.g. {global WWW HTML}).
  729.  
  730. Older versions of Alpha used to call a procedure with the same name
  731. as the menu (here 'ftpMenu') automatically whenever the menu was to
  732. be inserted.  The newer setup is a bit more verbose, but puts more
  733. control in your hands.
  734.  
  735. NOTE: If all you want to do is add a submenu to an already existing
  736. menu, go to the section 'Adding Items to Global Menus': you don't
  737. need the 'alpha::menu' statement, but actually need to write a 
  738. feature using 'alpha::feature'.
  739.  
  740. A menu-package is a set of code which builds and handles a standalone menu 
  741. which the user may choose as a global menu.  Examples are the ftpMenu, 
  742. filesetMenu, voodooMenu, internetConfigMenu, colorMenu and eudoraMenu (in 
  743. fact this last item, since it has a mode associated with it, could in fact 
  744. be rewritten as a mode with attached menu).  
  745.  
  746. Note: as of Alpha 7.1, you should use the command 'Menu -n ...' to build 
  747. menus, not 'menu -n ...'
  748. ===============================================================================
  749.  
  750.            Writing new features or extensions
  751.  
  752. An extension is a package which can be turned on once and then left 
  753. alone.  Something which requires turning on/off for different modes is 
  754. a feature.  In fact an extension is just implemented as a simple form 
  755. of feature.  A new extension must provide at the very least the 
  756. following line, preferably as the first non-comment line of one of its 
  757. files:
  758.  
  759.     alpha::extension 'NAME' 'VERSION'
  760.     
  761. It is better, if possible, if the extension can provide a small script to 
  762. carry out initialisation (which occurs when Alpha starts up, if the user
  763. has turned the package on).  If provided Alpha will use that script 
  764. rather than sourcing the entire extension file.  This means Alpha will
  765. start up more quickly.  Such a script is given by the following line:
  766.  
  767.     alpha::extension 'NAME' 'VERSION' 'SCRIPT'
  768.     
  769. A feature is more sophisticated and takes arguments of the following 
  770. form:
  771.  
  772.     alpha::feature 'NAME' 'VERSION' 'LIST OF MODES/GLOBAL' \
  773.       'INIT SCRIPT' 'ACTIVATE SCRIPT' 'DEACTIVATE SCRIPT'
  774.     
  775. Here is an example from the 'bibtexEngine' package:
  776.  
  777.     alpha::extension bibtexEngine 1.8 {
  778.         eventHandler GURL GURL GURLHandler
  779.     }
  780.  
  781. Here we didn't bother to turn the feature on and off, since its 
  782. initialisation was so trivial, and it won't interfere with other 
  783. modes at all.  Here's a more complex example:
  784.  
  785.     alpha::feature latexMathbb 1.0 {TeX Bib} {
  786.         newPref variable blackboardBoldSymbols "QZRN" TeX TeX::adjustMathbb
  787.         hook::register mode::init TeX::adjustMathbb TeX
  788.     } "" ""
  789.  
  790. We didn't bother with activation deactivation, since the definitions 
  791. don't take effect in other modes.  The simple 'extension' and 
  792. 'feature' commands make it very, very easy to extend Alpha's 
  793. functionality without messing with the user's preferences file, 
  794. without creating any '...+.tcl' extension files and without a complex 
  795. installation process.  Alpha simply maintains a database of all 
  796. 'extension' scripts, and evaluates at startup all scripts for 
  797. extensions which the user has activated.
  798.  
  799.            Writing new extensions (keyboard caveats)
  800.  
  801. Writers of any package for Alpha should pay some attention to the 
  802. problems which can arise with international keyboards.  Some bindings
  803. are simply not available on some keyboards.  For instance, on some
  804. keyboards, you need to use 'shift' to get the key '\' (unlike 
  805. american keyboards where it is a single keypress).  On such a keyboard
  806. there is no distinction between 'cmd-\' and 'shift-cmd-\'.  There is
  807. no simple workaround for this problem.
  808.  
  809. Possibilities are: (i) check the current keyboard definition and adjust
  810. bindings appropriately (based upon user feedback, presumably). (ii) let
  811. the bindings be user-definable either by using 'newPref binding' to
  812. define things, or by using a menu-scheme such as is used by HTML mode.
  813.  
  814.            Technicalities of different menu/feature/extensions
  815.  
  816. Menus and features and extensions are all treated in the same way by
  817. Alpha.  However each will have different associated information which
  818. will determine whether/in what section it appears in a dialog box.
  819. All this information is stored in the index::feature array.  
  820.  
  821. ...to be continued...
  822.  
  823. ===============================================================================
  824.            
  825.            Package preferences
  826.  
  827. Alpha stores preferences in three different places:
  828.  
  829. 1)    Global preferences are stored in the global->preferences menu, and
  830. are for variables/flags which maintain a value at the global scope.
  831.  
  832. 2)  Mode preferences are stored in the mode->preferences… item, and
  833. are for variables/flags which are stored in a mode array, but are transfered 
  834. into global scope when that mode is active (and hence temporarily override 
  835. any global preferences with the same names)
  836.  
  837. 3)  Packages may add to the global/mode preferences as they desire.  They 
  838. may also store preferences in their package array '${pkg}modeVars(…)'.  Such
  839. variables/flags are never transfered into the global scope.  Menu items to 
  840. edit a package's preferences should be placed in the 'global' menu, unless 
  841. they are global/mode prefs which should be added to Alpha's default 
  842. routines for use by the standard Alpha dialogs.  There is a standard proc
  843.  
  844.     package::addPrefsDialog Mypkg
  845.     
  846. which you can use to add an item to the global menu which will bring
  847. up the standard dialog to edit the contents of your '${pkg}modeVars(…)'
  848. array.
  849.  
  850.              Adding to the core prefs dialogs
  851.  
  852. If you wish to add items to any of the core preferences pages (Backups,
  853. Electric, Miscellaneous,...), you can do that like this:
  854.  
  855.     lunion varPrefs(Electric) var1 var2
  856.     lunion flagPrefs(Electric) flag1 flag2
  857.  
  858. All non-registered global preferences are added to the Miscellaneous page,
  859. so there is no need to do that automatically.  Make sure you don't add
  860. too much to any of these pages, because they will become too large to
  861. display correctly!
  862.  
  863. You can also add new core preferences pages.  All you have to do is create
  864. a new 'flagPrefs' entry (Alpha uses the command 'array names flagPrefs' to
  865. list the different pages):
  866.  
  867.     lunion flagPrefs(NewPage) flag1
  868.     
  869. Only add such pages if your package really does merit it; otherwise you're 
  870. better off just add a new global preferences dialog in the global menu.
  871.     
  872.              Defining a package's flags and variables
  873.  
  874. Preferences for a mode or package are defined as follows:
  875.  
  876.     # description of the preference
  877.     newPref type name {val 0} {pkg "global"} {pname ""} \
  878.         {options ""} {subopt ""}
  879.  
  880. Define a new preference variable/flag.
  881.  
  882. 'type' is one of:
  883.   'flag' (on/off only), 'variable' (anything), 'binding' (key-combo)
  884.   'menubinding' (key-combo which works in a menu), 'file' (input only),
  885.   'io-file' (either input or output)
  886.   
  887. 'name' is the var name, 
  888.  
  889. 'val' is its default value (which will be ignored if the variable
  890. already has a value)
  891.  
  892. 'pkg' is either 'global' to mean a global preference, or the name 
  893. of the mode or package (no spaces) for which this is a preference.
  894.  
  895. 'pname' is a procedure to call if this preference is changed by
  896. the user (no need to setup a trace).  This proc is only called
  897. for changes made through prefs dialogs or prefs menus created by
  898. Alpha's core procs.  Other changes are not traced.
  899.  
  900. Depending on the previous values, there are two optional arguments
  901. with the following uses:
  902.  
  903. TYPE:
  904.  
  905. variable:
  906.  
  907. 'options' is a list of items from which this preference takes a single
  908. item.
  909. 'subopt' is any of 'item', 'index', 'varitem' or 'varindex' or 'array', where
  910. 'item' indicates the pref is simply an item from the given list
  911. of items, 'index' indicates it is an index into that list, and
  912. 'var*' indicates 'items' is in fact the name of a global variable
  913. which contains the list. 'array' means take one of the values from an array.
  914. If no value is given, 'item' is the default
  915.  
  916. binding:
  917.  
  918. 'options' is the name of a proc to which this item should be bound.
  919. If options = '1', then we bind to the proc with the same name as
  920. this variable.  Otherwise we do not perform automatic bindings.
  921.  
  922. 'subopt' indicates whether the binding is mode-specific or global.
  923. It should either be 'global' or the name of a mode.  If not given,
  924. it defaults to 'global' for all non-modes, and to mode-specific for
  925. all packages.  (Alpha tests if something is a mode by the existence
  926. of modeMenus($mode))
  927.  
  928. menubinding:
  929.  
  930. menubindings are like bindings, but they don't have any automatic
  931. binding capabilities, and are restricted to key-sequences which the
  932. MacOS allows in menus.  Here is an example of how one might declare
  933. the 'QuickFind(Regexp)' dynamic pair using a menubinding pref:
  934.  
  935. declare the binding:
  936.  
  937.     «Alpha ƒ» newPref menubinding quickFind/quickFindRegexp <B/S
  938.     
  939. edit it if we like with:
  940.  
  941.     «Alpha ƒ» dialog::getAKey quickFind/quickFindRegexp <B/S
  942.     
  943. show the menu sequence if we like:
  944.     
  945.     «Alpha ƒ» menu::bind quickFind/quickFindRegexp -
  946.     <S<E<B/SquickFind <S<I<B/SquickFindRegexp
  947.     «Alpha ƒ» 
  948.  
  949. add it to a menu:
  950.  
  951.     «Alpha ƒ» eval menu::insert Search items end \
  952.         [menu::bind quickFind/quickFindRegexp -]
  953.     
  954. Have a look at the search menu.  It has a new dynamic item at the bottom!
  955.  
  956. Note that if you place a comment (one or more lines) just before the
  957. 'newPref' statement, it is scanned and stored by Alpha in a cache.  It
  958. can then be used to explain to the user what each preference does when
  959. the user selects 'describe mode' or presses the 'Help' button in a 
  960. preference dialog.
  961.  
  962.            Declaring help text for your preferences
  963.  
  964. Alpha has the ability to extract descriptive text for your preference
  965. items automatically, provided they are declared using 'newPref', and
  966. that you follow these guidelines.
  967.  
  968. If there is a comment (a line starting with '#') on the line/lines 
  969. preceding the newPref command, Alpha will (when it rebuilds the package 
  970. indices) store the text in that line/lines and use it to display helpful 
  971. information for that preference.  For example if you hit the 'help' button 
  972. in a dialog, Alpha will display this information.  Furthermore, in the 
  973. forthcoming Alpha 8.0, this information will be used for balloon help in 
  974. the prefs dialog related to your package/mode, provided you use the 
  975. standard mechanisms for declaring your mode/menu/feature/extension and you 
  976. use the standard preference mechanism supplied.  The format of the comment
  977. lines is simple for all except basic flags (newPref flag ...).  These will 
  978. display a different help text in balloons depending on their state.  There 
  979. are four possible states, although Alpha only really uses the first and 
  980. third such states at present.  The first state is the 'unchecked' state, 
  981. and the third the 'checked' state.  You declare separate help text for the 
  982. four possible states like this:
  983.  
  984.     # it is unchecked|it is dimmed|it is checked|it is checked and dimmed
  985.     newPref flag myFlag ...
  986.  
  987. In fact all help items have four possible states, although you will 
  988. usually not notice the other possibilities.  As you can see, Alpha uses '|' 
  989. to separate the different pieces of text.  Currently a typical help text 
  990. for a checkbox item should probably just look like this: 
  991.  
  992.     # To use a solid rectangular cursor, click this box||To use a thin 
  993.     # vertical cursor, click this box.
  994.     newPref flag blockCursor 0
  995.  
  996. Notice the syntax of the two messages.  Apple's interface guidelines
  997. give some advice for balloon help which you should follow for two 
  998. reasons: first, it's good advice for writing balloons, and second,
  999. Alpha assumes your messages are of the above form to use the text
  1000. effectively both for balloons, and for descriptive text.  Alpha will
  1001. automatically convert the above to:
  1002.  
  1003.     Block Cursor: To use a solid rectangular cursor, turn this item on.  To
  1004.     use a thin vertical cursor, turn this item off.
  1005.  
  1006. which is used in the descriptive dialogs Alpha sometimes provides.  This 
  1007. advice is of greatest importance for 'flag' preference items, since they
  1008. require two separate on/off balloon help texts.  Other items currently
  1009. just expect one piece of text.
  1010.  
  1011. A similar mechanism will soon be available for menus.
  1012.     
  1013.            Adding items to global menus
  1014.  
  1015. Using 'addMenuItem' is a bad idea, since many menus are dynamically
  1016. rebuilt and such items will be lost.  Furthermore, addMenuItem does
  1017. not work if you want to add dynamic items or sub-menus.  Also
  1018. creating a menu directly using 'Menu -n Name {list of items}' is
  1019. generally a bad thing to do when using Alpha version 7.0 or newer.
  1020.  
  1021. The solution to these problems is to use the following calls:
  1022.  
  1023.     menu::buildProc 'nameOfMenu' 'nameOfIts_build-proc' 
  1024.     menu::insert 'nameOfMenu' 'type' 'where' 'menuItem' ?menuItem...?
  1025.  
  1026. For technical reasons, if you use both types of call, always add the procs 
  1027. first.  You can add any list of menuItems using the latter of these two calls.  
  1028. The first registers a procedure which will be called to build a given menu.
  1029.  
  1030. Menus must be rewritten to support this new feature.  Currently all 
  1031. global menus File...Config support it, and several modes: Tcl, Perl, 
  1032. TeX.
  1033.  
  1034.              menu::buildProc
  1035.  
  1036. This proc registers a procedure to be the 'build-proc' for a given menu 
  1037. (tech note: just adds the build-proc to the "menu_build_procs" global array 
  1038. with the given menu's name as its index).  The build-proc procedure can do 
  1039. one of two things:
  1040.  
  1041. i) build the entire menu, including evaluating the 'Menu ...' command.
  1042. In this case the build proc should return anything which doesn't
  1043. begin 'build ...'  
  1044.  
  1045. If the proc returns anything beginning with 'Menu ..' that returned 
  1046. string is evaluated, but no insertions can take place.
  1047.  
  1048. ii) build up part of the menu, and then allow pre-registered menu
  1049. insertions/replacements to take-effect.  In this case the procedure
  1050. should return a list of the following (listed by index in the list):
  1051.  
  1052. 0: "build"
  1053. 1: list-of-items-in-the-menu
  1054. 2: menu procedure to call when an item is selected.  If nothing is given,
  1055. or if '-1' is given, then we don't have a procedure.  If "" is given,
  1056. we use the standard 'menu::generalProc' procedure.  Else we use the
  1057. given procedure.
  1058. 3: list of submenus which need building.
  1059. 4: over-ride for the name of the menu.
  1060.  
  1061. Here is an example of what gets returned by "menu::globalBuild", the 
  1062. build-proc for the menu named "global" (see Config:Global:):
  1063.  
  1064.         «Alpha ƒ» menu::globalBuild
  1065.         0:    build 
  1066.         1:    {
  1067.                 /p<U<BmenusAndFeatures… 
  1068.                             {Menu -n preferences {}} 
  1069.                 editPrefsFile 
  1070.                 (- 
  1071.                 compareWindowsPrefs… 
  1072.                 newDocumentPrefs… 
  1073.                 (- 
  1074.                 specialKeys… 
  1075.                 listGlobalBindings 
  1076.                 listPackages 
  1077.                 listAllBindings 
  1078.                 listFunctions 
  1079.                 (- 
  1080.                 rebuildPackageIndices
  1081.             } 
  1082.         2:    menu::globalProc 
  1083.         3:    preferences
  1084.         
  1085.         Note: the above output was reformated and numbered to make its structure 
  1086.         explicit, also note that any additions to what you see in 'Config:Global:' 
  1087.         are due to calls to "menu::insert".
  1088.  
  1089. You must register the build-proc before attempting to build the menu (i.e. 
  1090. call menu::buildProc.  
  1091.  
  1092. Once registered, any call of 'menu::buildSome <name of your menu>' will 
  1093. build your menu.
  1094.  
  1095.              menu::insert
  1096.  
  1097. nameOfMenu, type, where, then list of menuItems.  Here, type can be, either 
  1098. 'items', or 'submenu'.
  1099.  
  1100. Add given items to a given menu, provided they are not already there.
  1101. Rebuild that menu if necessary.
  1102.  
  1103. There are also procs 'menu::removeFrom' which does the opposite of
  1104. this one, and 'menu::replaceWith' which replaces a given menu item
  1105. with others.
  1106.  
  1107. There is a difference between 'menu::insert Utils submenu 2 compare' and 
  1108. 'menu::insert Utils items 2 [list Menu -n compare {}]'.  The former 
  1109. registers the submenu as a submenu which will be built automatically by a 
  1110. call to 'menu::buildSome' each time the parent menu is rebuilt, the latter 
  1111. does no such thing.  You will, therefore normally wish to use the first 
  1112. form, but occasionally there will be situations when the latter would be 
  1113. better.
  1114.  
  1115. Here is a simple example:
  1116.  
  1117.     alpha::extension compareWindows 0.1 {
  1118.         Bind 0x32    <X> compare::windowsInPlace
  1119.         Bind '1'  <X> compareOpt
  1120.         Bind 0x32    <sX> compareNext
  1121.         Bind 0x12    <sX> compareOptNext
  1122.         menu::insert Utils submenu 2 compare
  1123.         menu::insert "compare" items end windowsInPlace
  1124.     }
  1125.  
  1126. We first add a submenu after the second item in the Utils menu, called
  1127. 'compare', and then add to the end of that compare menu. This code works 
  1128. whether the package is active at startup or not.  Here is a more 
  1129. complex example:
  1130.  
  1131.     alpha::extension documentProjects 1.2 {
  1132.         alpha::package require elecCompletions
  1133.         alpha::package require newDocument
  1134.         menu::buildProc "Current Project" Docproj::currentMenu
  1135.         menu::insert global items end \
  1136.             "documentProjectPrefs…" "userDetails…" \
  1137.             "<E<SremoveDocumentTemplate…" "<S<BeditDocumentTemplate…" \
  1138.             "<SnewDocumentTemplate…" \
  1139.             "<E<SremoveProject…" "<S<BeditProject…" "<SnewProject…"
  1140.         menu::insert global submenu end {Current Project}
  1141.         newPref binding updateFileVersion "/f<U" Docproj
  1142.         menu::insert fileUtils items end \
  1143.             "showInFinder" \
  1144.             "(-" \
  1145.             "updateDate" \
  1146.             "[menu::bind DocprojmodeVars(updateFileVersion) -]"
  1147.         lunion elec::MenuTemplates "createHeader" "newDocument"
  1148.         menu::insert elec items end \
  1149.             {Menu -n functionComments -p menu::fileUtils {
  1150.             "/efunctionComment"    
  1151.             "/e<IfunctionCommentSimple" 
  1152.             "/e<OfunctionCommentWithAuthor" 
  1153.             "/e<UfunctionCommentUpdate" 
  1154.         }}
  1155.         set newDocument::handlers(documentProjects) Docproj::newHandler
  1156.     }
  1157.  
  1158. The 'documentProjects' package adds items to many different menus,
  1159. including the 'elec' menu (from the elecCompletions package).
  1160.  
  1161. ===============================================================================
  1162.  
  1163.            Package testing
  1164.  
  1165. The 'alpha::package' command is very similar to Tcl 8.0's standard
  1166. 'package' command, but differs in a few respects.  When Alpha upgrades
  1167. to Tcl 8, this will allow both features to coexist happily.  You can use
  1168. 'alpha::package' to check/request the presence of other packages.
  1169.  
  1170.     alpha::package require NAME ?VERSION?
  1171.     
  1172. Other sub-commands are 'exists' 'names' 'versions' 'vcompare' 'vsatisfies'
  1173. 'forget' 'uninstall' and 'mode', 'menu' and 'package'.  These last three
  1174. mimic the usual alpha::mode alpha::menu and alpha::package commands.
  1175.  
  1176.     alpha::package require ?-extension -mode -menu? name version
  1177.     alpha::package exists ?-extension -mode -menu? name version
  1178.     alpha::package names
  1179.     alpha::package uninstall name version [this-file|this-directory|script]
  1180.     alpha::package vcompare v1 v2
  1181.     alpha::package vsatisfies v1 v2
  1182.     alpha::package versions ?-extension -mode -menu? name
  1183.     alpha::package type name
  1184.     alpha::package info name
  1185.     alpha::package maintainer name version {name email web-page}
  1186.     alpha::package help name version [file 'name'|text]
  1187.  
  1188. Equivalent to alpha::mode, alpha::menu and alpha::extension
  1189.  
  1190.     alpha::package mode ...
  1191.     alpha::package menu ...
  1192.     alpha::package extension ...
  1193.  
  1194. For extensions only:
  1195.  
  1196.     alpha::package forget name version
  1197.  
  1198. ..
  1199.  
  1200. ===============================================================================
  1201.  
  1202.            Installation
  1203.  
  1204. There is a new install mode 'Inst' which adds the Install menu.
  1205. Install mode is trigerred when a file's name ends in 'Install'
  1206. or 'INSTALL', or when the first line of the file contains the
  1207. letters 'install', provided in this last case, that the file
  1208. is not in Alpha's Tcl hierarchy.  This last case is useful so
  1209. that a single .tcl file can be a package and be installed by
  1210. Alpha using these nice scripts, without the need for a separate
  1211. install-script-file.  However once that .tcl file is installed,
  1212. if you open it you certainly wouldn't want it opened in Install mode!
  1213.     
  1214. So, single file packages should just include 'install' somewhere in
  1215. their first line.  Multi-file packages should include an install
  1216. file.  Call this file 'OPEN TO INSTALL' or something like that.
  1217. When the user opens it, Inst mode is activated, and the user can
  1218. use the install menu to install your package.  If you wish the
  1219. installation dialog to be activated automatically, include the
  1220. text (auto-install) in the first line of the file.
  1221.  
  1222. Most packages will _not_ need anything other than the existence of
  1223. such a file.  In fact a file called 'OPEN TO INSTALL' containing the
  1224. single line '(auto-install)' will do the trick nicely.
  1225.  
  1226. Alpha will scan the installation file directory and make a nice
  1227. dialog with 'Easy install' and 'Custom install' options.  Alpha
  1228. knows where Modes, Menus, Completions, Bug fixes, Tools, Packages,
  1229. Extensions, ... all go in the Alpha hierarchy.
  1230.  
  1231.              Package-specific installation over-rides
  1232.  
  1233. You can over-ride the default behaviour by providing a 'xxx_install.tcl'
  1234. file in the file directory.  In such a case that file will be sourced.
  1235. See "install.tcl" for some more information on how to over-ride the
  1236. default behaviour.  You will usually use the following procedure:
  1237.  
  1238.     install::packageInstallationDialog 'NAME' 'DESCRIPTION' ...
  1239.  
  1240. Optional arguments are as follows:
  1241.  
  1242.     -ignore {list of files to ignore}
  1243.     -remove {list of files to remove from Alpha hierarchy}    
  1244.     -forcequit '0 or 1'  
  1245.         (forces the user to quit; default 0)
  1246.     -require {Pkg version Pkg version …}
  1247.         e.g. -require {Alpha 7.0b1p2 elecCompletions 7.99}
  1248.     -provide {Pkg version Pkg version …}
  1249.  
  1250. and 
  1251.  
  1252.     -SystemCode -Modes -Menus -BugFixes -Completions -Packages
  1253.     -ExtensionsCode -UserModifications -Tools -Home
  1254.  
  1255. which force the placement/use of the following lists of files.  To
  1256. require an exact package version use:
  1257.  
  1258.     -require {Alpha {-exact 7.0b2} elecCompletions {-exact 8.1.2} ...}
  1259.  
  1260. Also, rather than having separate 'OPEN-TO-INSTALL' and '*install.tcl'
  1261. files, if the former file contains the text 'auto-install-script' in
  1262. its first line, it will be used as a Tcl script, and sourced rather than
  1263. opened.  Ensure that first line begins with a '#' or an error will
  1264. result.  (You can open that file for editing, without triggering the
  1265. install script if you hold down a modifier key).
  1266.  
  1267. If you gave the -provide option, Alpha checks those items with what
  1268. the user has already installed and warns if an item has already been 
  1269. installed and is not older than the one about to be installed.
  1270.  
  1271.              Uninstalling packages
  1272.  
  1273. Each package should provide a 'alpha::package uninstall name version script' 
  1274. statement.  When your script is evaluated, the global variable 'pkg_file' 
  1275. will be initialised to the full name of the file which contains the 
  1276. uninstall command.  Therefore for a single file package, the following is 
  1277. normal:
  1278.  
  1279.     alpha::package uninstall developerUtilities 1.1 {removeFile $pkg_file}
  1280.  
  1281. However, a much more convenient form of the above command is also possible, 
  1282. and most packages use it --- you may combine declaration and uninstall lines 
  1283. like this:
  1284.  
  1285.     alpha::extension developerUtilities 1.1 {
  1286.         # declaration script
  1287.     } uninstall {
  1288.         # uninstall script
  1289.     }
  1290.     
  1291. i.e. there are two extra optional arguments to the 'package' command.
  1292. Finally to be even simpler, if the command is 'uninstall this-file',
  1293. then that is equivalent to {removeFile $pkg_file}, and if the command
  1294. is 'uninstall this-directory', then that entire file's directory is
  1295. removed.  Make sure you don't use 'uninstall this-directory' for a
  1296. single-file package, or you'll wipe out the entire package hierarchy.
  1297. Similarly alpha::mode and alpha::menu commands may contain an optional
  1298. uninstall script like the above.
  1299.  
  1300.              Disabling packages
  1301.  
  1302. A package can add a script to be evaluated when the user disables the
  1303. package.  You do that with the additional command 'disable':
  1304.  
  1305.     alpha::extension developerUtilities 1.1 {
  1306.         # declaration script
  1307.     } disable {
  1308.         # disable script
  1309.     }
  1310.  
  1311. Complex packages will probably not provide such a script.  In such a
  1312. case the user would have to restart Alpha to disable the package
  1313. correctly.
  1314.  
  1315.              Tcl index files
  1316.  
  1317. You probably know that Tcl uses 'index' files to find procedures which
  1318. are called but not yet defined.  Your installation directories may
  1319. contain index files if you desire, but they are only installed if no
  1320. current index file exists in the installation location.  You cannot
  1321. override this behaviour.
  1322.  
  1323. ===============================================================================
  1324.            
  1325.            Vince's Additions Support:
  1326.  
  1327. This is primarily for new modes. 
  1328.  
  1329.              Source-Header files
  1330.      
  1331. If your mode makes distinctions between 'Source' and 'Header' 
  1332. files, you should define these two variables
  1333.  
  1334.     newPref var sourceSuffices { .cc .cp .cpp .c .icc } C++
  1335.     newPref var headerSuffices { .h .hh } C++
  1336.  
  1337.              Completions
  1338.  
  1339. If you mode is to use a variety of completion routines, define
  1340. an array entry like this:
  1341.  
  1342.     set completions(${mode}) \
  1343.         {completion::cmd completion::electric completion::word}
  1344.  
  1345. For the meaning of the list items, look at "elecCompletion.tcl".  If
  1346. all you need is the basic 'Command', 'Electric' and 'Word' completion
  1347. routines, the above list will do the trick.  You will then need to
  1348. define a variable ${mode}cmds like this:  
  1349.  
  1350.     set Ccmds { #elseif #endif #include class default enum for register return 
  1351.      struct switch typedef volatile while }
  1352.  
  1353. It MUST be in alphabetical order.  For electric template insertions, you need
  1354. to create an array with entries like these:
  1355.     
  1356.     set Celectrics(for) " (•init•;•test•;•increment•)\{\n\t•loop body•\n\}\n••"
  1357.     set Celectrics(while) " (•test•)\{\n\t•loop body•\n\}\n••"
  1358.     set Celectrics(switch) " (•value•)\{\n…case •item•:\n\t•case body•\n…default:\n\t•default body•\n\}\n••"
  1359.     set Celectrics(case) " •item•:\n…•case body•\ncase"
  1360.  
  1361.              Mode-specific completions
  1362.  
  1363. If your mode has its own completion routines, they must be named
  1364. ${mode}::Completion::Type, where 'Type' is an entry in the above
  1365. list.  You'll have to know a reasonable bit of Tcl to write your
  1366. own routines like that.  Look at C::Completion::Class for a relatively
  1367. simple example.
  1368.  
  1369.              Electric menu templates
  1370.  
  1371. ${mode}Templates is a list of names which are added to the electric 
  1372. menu's 'Templates' sub-menu.  The real procs should be called 
  1373. 'file::${name}'.
  1374.  
  1375.              Vince's Additions summary
  1376.  
  1377. That's it!  Take a look at "scilabMode.tcl" as a simple example of a new mode
  1378. which makes use of Vince's Additions.
  1379.  
  1380. ===============================================================================
  1381.  
  1382.